View AVR32795_1593151.PDF datasheet online --- IC-ON-LINE

Datasheet File OCR Text:

AVR32795: using the gnu linker scripts on avr uc3 devices features ? basic gnu linker script concepts ? 32-bit avr ? uc3? gnu linker scripts ? controlling the location of functions and variables in the flash 1 introduction this document highlights the main purpose of the gnu linker script, which is to control the location of code and variables in the executable. figure 1-1. avr gnu toolchain build steps. 32-bit microcontrollers application note rev. 32158a-avr-01/11
2 AVR32795 32158a-avr-01/11 2 memory map the atmel ? avr uc3 microcontroller architecture has a 32-bit memory space and separate memory types (program and data) connected with distinct buses. such a memory architecture allows the proc essor to access both program and data memories at the same time. each me mory type has its own address space. figure 2-1. example of the atmel at32uc3a3256 memory map.
AVR32795 3 32158a-avr-01/11 3 basic linker script concepts 3.1 sections the linker combines input files (object file format) into a single output file (executable). each object file has, among other things, a list of sections. we refer to a section in an input file as an input section. similarly, a section in the output file is an output section. each section in an object file has a name and a size. most sections also have an associated block of data (the section contents). 3.2 section properties a section may be marked as loadable, which means that its contents should be loaded into memory when the executable is run. a section with no contents may be allocatabl e, which means that an area in memory should be set aside, but nothing in particular should be loaded there (and, in some cases, this memory must be zeroed out). a section which is neither loadable nor alloca table typically contains some sort of debugging information. 3.3 vma and lma every loadable or allocatable output section has two addresses. the first is the vma, or virtual memory address. this is the address the section will have when the output file is run. the second is the lma, or l oad memory address. this is the address at which the section will be loaded. in most cases the two addresses will be the same. an example of when the lma and vma might be different is when a data section is loaded into rom, and then copied into ram when the program starts up (a technique often used to initialize global variables in a rom-based system). in this case, the rom address would be the lma and the ram address would be the vma. 3.4 symbols every object file also has a list of symbols, known as the symbol table. a symbol may be defined or undefined. each symbol has a name, and each defined symbol has an address, among other information. the compilation of a c or c++ program in to an object file will generate a defined symbol for every defined function and glob al or static variable. every undefined function or global variable which is referenced in the input file will become an undefined symbol. 3.5 well-known sections .text: usually contains the code, and is usually loaded to a non-volatile memory, such as the internal flash. .data: initialized data; usually contains initialized variables. .bss: usually contains non-initialized data.
4 AVR32795 32158a-avr-01/11 note the section, properties, vma, and lma are available in an object file or output file by using the avr32-objdump program with the -h option. for example: idx name size vma lma file off algn 0 .reset 00002004 80000000 80000000 00001000 2**2 contents, alloc, load, readonly, code 1 .got 00000000 0000001c 80003634 0000501c 2**2 contents, alloc, load, reloc, data 2 .init 0000001a 80002004 80002004 00003004 2**2 contents, alloc, load, readonly, code 3 .text 00001074 80002020 80002020 00003020 2**2 contents, alloc, load, readonly, code 4 .exception 00000200 80003200 80003200 00004200 2**9 contents, alloc, load, readonly, code 5 .fini 00000018 80003400 80003400 00004400 2**2 contents, alloc, load, readonly, code 6 .rodata 00000208 80003418 80003418 00004418 2**2 contents, alloc, load, readonly, data 7 .dalign 00000004 00000004 00000004 00000000 2**0 alloc 8 .ctors 00000008 00000008 80003620 00005008 2**2 contents, alloc, load, data 9 .dtors 00000008 00000010 80003628 00005010 2**2 contents, alloc, load, data 10 .jcr 00000004 00000018 80003630 00005018 2**2 contents, alloc, load, data 11 .data 00000820 0000001c 80003634 0000501c 2**2 contents, alloc, load, data 12 .bss 0000015c 00000854 00000854 00000000 2**2 alloc 13 .heap 0000e650 000009b0 000009b0 00000000 2**0 alloc note the symbols are available in an object or output file by using t he avr32-nm program, or by using the avr32-objdump program with the -t option.
AVR32795 5 32158a-avr-01/11 4 default versus specific linker script the linker always uses a linker script. if none is explicitly supplied, the linker will use a default script that is compiled into the linker executable. the avr gnu toolchain default linker scripts are under the directory: c:/program files/atmel/avr tools/avr (32) toolchain/avr32/lib/ldscripts/ other linker scripts can be supplied by using the ?t command line option (or the long form: ?script= ). when this is done, the linker sc ript specified will replace the default linker script. extensions of the gnu toolchain linker scripts and their meanings: .x : default linker script, for ?regular? executables. . xbn : default linker script used when the ?n option is specified; mix text and data on the same page; don't align data. .xn : default linker script used when the ?n option is specified; mix text and data on the same page. .xr : default linker script used when the ?r option is specified; link without relocation. .xu : default linker script used when the ?ur option is specified; link without relocation, create constructors. .xw : linker script to use for writable .rodata section.
6 AVR32795 32158a-avr-01/11 5 gnu linker script walkthrough /* ? */ : comments output_format("elf32-avr32", "elf32-avr32", "elf32-avr32") : the output_format command names the bfd format to use for the output file. in this case, this is strictly equivalent to output_format("elf32-avr32") output_format(default, big, little) : output_format is usable with three arguments to use different formats based on the ?eb and -el command line options. this permits the linker script to se t the output format based on the desired endianness. output_arch(avr32:uc) : specify a particular output machine architecture. entry(_start) : set the first instruction to execute in a program (called the entry point). 5.1 memory command describes the location and size of blocks of memory in the target. memory { flash (rxai!w) : origin = 0x80000000, length = 256k intram (wxa!ri) : origin = 0x00000004, length = 0x0000fffc userpage : origin = 0x80800000, length = 0x00000200 } ? r : read-only section ? w : r/w section ? x : executable section ? a : allocatable section ? i : initialized section ? ! : invert the sense of the following attributes the linker will use the region attributes to select the memory region for the output section that it creates (if not explicitly mentioned later in the script). once a memory region is defined, the linke r script can direct the linker to place specific output sections into that memory region. 5.2 phdrs command the elf object file format uses prog ram headers, aka segments. the program headers describe how the program should be loaded into the target memory. phdrs { flash pt_load; name used in the linker script to refer to that memory region optional list of attributes this pro g ram header describes a se g ment to be loaded from the file
AVR32795 7 32158a-avr-01/11 intram_align pt_null; intram_at_flash pt_load; intram pt_null; userpage pt_load; } to place an output section in a particular segment, use the :phdr output section attribute. when the executable is programmed to target, only the loadable segments should be programmed. note there are types other than pt_load and pt_null (refer to the gcc linker scripts documentation for details). 5.3 sections command tells the linker how to map input sections into output sections, and how to place the output sections in memory. sections { sections-command sections-command ... } each sections command may be one of the following: ? an entry command ? a symbol assignment ? an output section description ? an overlay description 5.3.1 symbol assignment a value can b e assigned to a symbol. this will define the symbol as a global symbol. example 1: /* use a default stack size if stack size was not defined. */ __stack_size__ = defined(__stack_size__) ? __stack_size__ : 4k; example 2: provide (__executable_start = 0x80000000); . = 0x80000000; note the special symbol ?.? is the location counter. indicates an unused ( for loadin g) pro g ram header indicates an unused ( for loadin g) pro g ram header
8 AVR32795 32158a-avr-01/11 note if the address of an output section is not sp ecified, the address is set from the current value of the location counter. the location co unter is then incremented by the size of the output section. at the start of the sections command, it equals zero by default. 5.3.2 output section description most p rograms consist only of code, initialized data, and uninitialized data. these will be in the .text , .data , and .bss sections, respectively. fo r most programs, these are also the only sections that appear in the input files. 5.3.2.1 sections sections { . = 0x80000000; .text : { *(.text) } . = 0x00000000; .data : { *(.data) } .bss : { *(.bss) } } the first line inside the sections command of the above example sets the value of the special symbol ?.?, which is the location co unter. if any address of an output section is specified in some other way, the address is set from the current value of the location counter. the location counter is then increm ented by the size of the output section. at the start of the sections command, the location counter has the value 0. the second line defines an output section, .text . within the curly braces after the output section name, it lists the names of t he input sections that should be placed into this output section. the ?*? is a wildcard, which matches any file name. the expression *(.text) means all .text input sections in all input files. because the location counter is 0x80000000 when the output section .text is defined, the linker will set the address of the .text section in the output file to be 0x80000000. the remaining lines define the .data and .bss sections in the output file. the linker will place the .data output section at address 0x00000000. after the linker places the .data output section, the value of the location counter will be 0x00000000 plus the size of the .data output section. the effect is that the linker will place the .bss output section immediately after the .data output section in memory. the linker will ensure that each output section has the required alignment, by increasing the location counter if necessary. in this example, the specified addresses for the .text and .data sections will probably satisfy any alignment constraints, but the linker may have to create a small gap between the .data and .bss sections. set the value of the location counter list the names of the input sections that should be placed into this output section: ?all .text input sections in all input files? section name
AVR32795 9 32158a-avr-01/11 figure 5-1. memory mapping. 5.3.2.2 text .text : { *(.text .stub .text.* .gnu.linkonce.t.*) keep (*(.text.*personality*)) /* .gnu.warning sections are handled specially by elf32.em.*/ *(.gnu.warning) } >flash at>flash :flash =0xd703d703 note when link-time garbage collection is in use (-gc-sections), it is often useful to mark sections that should not be eliminated. this is accomplished by surrounding an input section's wildcard entry with keep(). set the fill pattern for an entire section assign a section to a previously defined segment (cf phdrs command) specify a memory region for the .text section lma assign a section to a previously defined region of memory (cf. memory command ) the program may use external libraries (for example, gcc libraries, newlib) that use specific input sections
10 AVR32795 32158a-avr-01/11 6 examples 6.1 controlling the location of functi ons and variables in the f lash 6.1.1 process flow a. define a custom section, .flash_nvram , located in flash: a.1. handle a default or pre-defined size for this section: /* use a default flash nvram size if flash nvram size was not defined. */ __flash_nvram_size__ = defined(__flash_nvram_size__)?__flash_nvram_size__:4k; a.2. describe the output section, .flash_nvram : .flash_nvram origin(flash) + length(flash) - __flash_nvram_size__ : { *(.flash_nvram) } >flash at>flash :flash_nvram b. locate a variable in a custom section, .flash_nvram : ? extensions to the c language family: o specifying attributes of variables __attribute__((__section__(".flash_nvram"))) static int flash_nvram_data; c. locate a function in a custom section, .flash_nvram : ? extensions to the c language family: o declaring attributes of functions __attribute__ ((__section__(".flash_nvram"))) void func(void) {?} note placing a variable or a function at a specific address has to be done through the linker script (place the custom sect ion at the specific address). include all input sections .flash_nvram vma of this output section assign this section to a program segment (cf phdrs{ } ) specify the memory region flash for the section?s lma assign this section to the flash region of memory (cf. memory{ } )
AVR32795 11 32158a-avr-01/11 6.1.2 related examples in the software framework ? drivers/flashc/flash_exam ple/: controlling the location of a variable in flash ? drivers/cpu/mpu/example/ : controlling the location of a function in flash 6.2 controlling the location of f unctions in int ernal ram 6.2.1 process flow a. define a custom output section, .ram_fcts , with vma in ram and lma in flash: .ram_fcts : { *(.ram_fcts.*) } >intram at>flash :flash b. locate a function in a custom section, .ram_fcts : ? extensions to the c language family: o declaring attributes of functions __attribute__ ((__section__(".ram_fcts"))) void func(void) {?} c. the startup routine is responsible for copying the .ram_fcts lma (in flash) to the .ram_fcts vma (in intram ), as is done for the .data section . 6.2.2 related examples examples of a startup routine implem entation can be found in the avr software framework under utils/startup_files/gcc/ in asf v1 and under utils/startup/startup_uc3.s in asf v2. an example using the same method can be found here: avr32749 application note : software workaround implementation for the erratum flash read-after-write for at32uc3a0512 / at32uc3a1512 revision e, h and i. include all input sections .ram_fcts assign a section to a previously defined segment (cf phdrs command ) specify a memory region for the .text section lma assign this section?s vma to the intram region of memory (defined in memory{ } )
12 AVR32795 32158a-avr-01/11 6.3 controlling the location of variables and the heap in external sdram 6.3.1 process flow a. linker script customization a.1. adding the external sdram memory ( memory{} ) memory { flash (rxai!w) : origin = 0x80000000, length = 0x00040000 intram (wxa!ri) : origin = 0x00000004, length = 0x0000fffc eram0 (wxa!ri) : origin = 0xff000000, length = 0x00008000 eram1 (wxa!ri) : origin = 0xff008000, length = 0x00008000 sdram (wxa!ri) : origin = 0xd0000000, length = 0x02000000 userpage : origin = 0x80800000, length = 0x00000200 } a.2. adding the external sdram segments ( phdrs{} ) phdrs { flash pt_load; intram_align pt_null; intram_at_flash pt_load; intram pt_null; sdram_at_flash pt_load; sdram pt_null; userpage pt_load; } a.3. defining two output sections for variables placed in external sdram ( .data_sdram , .bss_sdram ) . = origin(sdram); .data_sdram origin(sdram) : { provide(_data_sdram = .); *(.data_sdram) . = align(8); provide(_edata_sdram = .); } >sdram at>flash :sdram_at_flash set the location counter to sdram start address set the vma of . data sdram will be used b y the startup routine for data init
AVR32795 13 32158a-avr-01/11 provide(_data_sdram_lma = absolute(loadaddr(.data_sdram))); .bss_sdram : { provide(__bss_sdram_start = .); *(.bss_sdram) provide(_bss_sdram_end = .); } >sdram at>sdram :sdram note because the program header sdram was defined as pt_null , the .bss_sdram section won?t be loaded to target (which is ok because the .bss section is supposed to hold uninitialized data). and so the at>sdram is unnecessary and ignored. this section will just be zeroed out in the startup routine. note definitions: _data_sdram : vma address of the start of the .data_sdram section _data_sdram : vma address of the end of the .data_sdram section _data_sdram_lma : lma start address of the .data_sdram section >sdram at>flash :sdram_at_flash >sdram : vma of .data_sdram in external sdram at>flash : lma of .data_sdram (in flash) :sdram_at_flash : specified as loadable in phdrs{} (for the data init value) will be used b y the startup routine for data init will be used by the startup routine for zero init assign a section to a previously defined segment (cf phdrs{} ) specif y the memor y re g ion sdram for the section?s lm a assign this section?s vma to the region of memory sdram ( defined in m emory { } )
14 AVR32795 32158a-avr-01/11 a.4. specifying the size and location of the heap to external sdram .heap : { __heap_start__ = .; *(.heap) . = __heap_size__; __heap_end__ = .; } >sdram at>sdram :sdram note because the program header sdram was defined as pt_null , the .heap section won?t be loaded to target. and so the at>sdram is unnecessary and ignored. b. initialization of the sdram controller: ? when: before the first sdram access, which is performed during the startup process (for .data_sdram and .bss_sdram sections initialization) ? how: using the startup customization api ( _init_startup() ), which is called by the startup routine befor e doing the sdram access c. startup routine customization c.1. call the startup cu stomization function: call _init_startup : this is when the sdram c ontroller must be initialized c.2. .data_sdram and .bss_sdram sections initialization: ? load initialized external sdram data having a global lifetime from the .data_sdram lma section using the symbols previously defined in the linker script ( _data_sdram and _edata_sdram (the vma addresses), _data_sdram_lma (the lma start address)) assign a section to a previously defined segment (cf phdrs{} ) specify the memory region s dram for the section?s lma assign this section?s vma to the region of memory sdram (defined in m emory{ } ) vma address symbol used by the malloc gnu lib force the .heap section to be of size heap size vma address symbol used by the malloc gnu lib
AVR32795 15 32158a-avr-01/11 ? clear uninitialized external sdra m data having a global lifetime in the .bss_sdram section using the symbols previously defined in the linker script ( _bss_sdram_start and _bss_sdram_end (vma addresses)) d. using dynamic allocation: use malloc() and free() ?as usual? e. assigning an initialized variable to external sdram: __attribute__((__section__(".data_sdram"))) static int allgoodchildrengotoheaven[7] = { 1,2,3,4,5,6,7 }; f. assigning a non-initialized variable to external sdram: __attribute__((__section__(".bss_sdram"))) static int hellogoodbye; 6.3.2 details (documentation and source code) avr327 33 application note : placing data and the heap in external sdram.
16 AVR32795 32158a-avr-01/11 7 specific linker script examples ? the avr software framework provi des generic linker scripts under utils/linker_scripts/ or specific linker scripts for some examples; these scripts have a .lds extension (the extension doesn?t matter). ? drivers/flashc/flash_example/: controlling the location of variables in flash ? drivers/cpu/mpu/example/ : controlling the location of a function in flash ? application note avr32733 : placing data and the heap in external sdram
AVR32795 17 32158a-avr-01/11 8 frequently asked questions q: how can i use my own linker script instead of the default one inside a 32-bit avr project? a: by default, avr32-gcc uses the default lin ker script from the avr gnu toolchain. to use your own linker script in a 32-bit atmel avr32 studio ? project, use the following procedure: ? copy your linker script in the ro ot of your project (use the import command, or simply copy/paste) ? open the project properties view (pro perties item from the contextual menu) ? select the tool settings tab ? select the avr32/gnu c linker -> miscellaneous item ? add -t../my_linker_script.lds to the linker flags command line your project is now ready to link with your own linker script. q: how can i declare a variable at a specific location of the flash memory? a: to do so with gcc, a specific section must be created at link time. here is an example of how to place a string variable at address 0x80010000: 1. declare the variable, specifying location in the .testloc section: const char string[] __attribute__ ((section (".testloc"))) = "string at fixed address"; 2. create the section in the linker options: ? open the project properties: highlight the project name and press alt+enter ? select the c/c++ build / settings category ? select the tool settings tab ? expand the avr32/gnu linker and high light the miscellaneous item ? in the linker flags field, add the -wl,-section-start=.testloc=0x80010000 option refer also to the screen shot below.
18 AVR32795 32158a-avr-01/11 q: when compiling the arv software framework examples, i got the following kinds of warnings: ld: uc3a0512-ctrlpanel.elf: warning: allocat ed section ?.dalign? not in segment ld: uc3a0512-ctrlpanel.elf: warning: allocated section ?.bss? not in segment ld: uc3a0512-ctrlpanel.elf: warning: allocated section ?.heap? not in segment ld: uc3a0512-ctrlpanel.elf: warning: allocated section ?.stack? not in segment what are these warnings? a: these are normal warnings, and you don't need to care about them. here is an explanation of these warnings: when using the default linker scripts provided with avr32-gcc, the elf load program headers are generated automatically from the output sections, including bss and the stack which are only allocated areas. in its current revision, avr32program programs allocate load program headers that do not have to be filled with data from the elf file, which wastes time. this avr32program behavior will be changed in a future release, but until this is achieved, the linker scripts provided wi th avr software framework are modified to place the allocated-only output secti ons in null elf program headers, which are ignored by avr32program, explai ning the warnings when linking.
AVR32795 19 32158a-avr-01/11 q: how can i create a 32-bit avr32 studio project from an existing standalone project that has its own makefile and linker script? a: here is the step-by-step procedure to import your existing project into 32-bit avr32 studio and reuse the makefile and linker scripts of the project: 1. create an empty project: ? open the new wizard selection: menu file -> new -> other ? expand the c folder and highlight the avr32 c project (make) item ? click next to open the new project wizard ? select the target mcu from the list, enter a project name, and click finish 2. add the existing source code and makefile: ? open the new wizard selection again: menu file -> new -> other ? expand the general folder and highlight the folder item ? click next to open the new folder wizard ? click on advanced>>, and check the link to folder in the file system box ? browse to the location of your exis ting stand-alone project, and click finish 3. create a make target: ? in the project explorer view, browse to the folder that contains the makefile ? right-click on the makefile file, and se lect the create make target item ? enter a name in the target name: field (for example, build), and click create note other targets could be add ed by repeating the above steps. note the make target creations depend on the keywords defined in the makefile: 4. build the make target: ? in the project explorer view, right-click on the project name, and select the build make target item ? select the make target to build, and click finish
20 AVR32795 32158a-avr-01/11 9 references the official gnu ld linker documentation: http://sourceware.org/binutils /docs-2.19/ld/index.html http://sourceware.org/binutils/docs-2.19/ld/scripts.html#scripts using the gnu comp iler collection: http://gcc.gnu.org/onlinedocs/ : online html or pdf document 10 support atmel has several support channels available: ? web portal: http://support.atmel.no/ all atmel microcontrollers ? email: avr@atmel.com all avr products ? email: avr32@atmel.com all 32-bit avr products please register on the web portal to gai n access to the following services: ? access to a rich faq database ? easy submission of technical support requests ? history of all past support requests ? register to receive atmel microcontroller newsletters
AVR32795 21 32158a-avr-01/11 11 table of contents features ............................................................................................... 1 1 introduc tion ...................................................................................... 1 2 memory map..................................................................................... 2 3 basic linker scr ipt concepts ........................................................... 3 3.1 sections............................................................................................................... 3 3.2 section pr operties ............................................................................................... 3 3.3 vma and lma ..................................................................................................... 3 3.4 sym bols............................................................................................................... 3 3.5 well-known sections............................................................................................ 3 4 default versus spec ific linker script............................................... 5 5 gnu linker scrip t walkth rough ....................................................... 6 5.1 memory command ........................................................................................... 6 5.2 phdrs command ............................................................................................... 6 5.3 sections command ......................................................................................... 7 5.3.1 symbol assignm ent ................................................................................................... 7 5.3.2 output section descrip tion ......................................................................................... 8 6 exampl es ........................................................................................ 10 6.1 controlling the location of functi ons and variables in the flash ......................... 10 6.1.1 proce ss flow ............................................................................................................ 1 0 6.1.2 related examples in the software framework.......................................................... 11 6.2 controlling the location of f unctions in inte rnal ra m......................................... 11 6.2.1 proce ss flow ............................................................................................................ 1 1 6.2.2 related examples.................................................................................................... 11 6.3 controlling the location of variables and the heap in ex ternal sdram ............ 12 6.3.1 proce ss flow ............................................................................................................ 1 2 6.3.2 details (documenta tion and sour ce co de) ............................................................... 15 7 specific linker script exam ples..................................................... 16 8 frequently asked questi ons.......................................................... 17 9 refere nces...................................................................................... 20 10 suppor t ......................................................................................... 20 11 table of conten ts......................................................................... 21
32158a-avr-01/11 atmel corporation 2325 orchard parkway san jose, ca 95131 usa tel: (+1)(408) 441-0311 fax: (+1)(408) 487-2600 www.atmel.com atmel asia limited unit 01-5 & 16, 19f bea tower, milennium city 5 418 kwun tong road kwun tong, kowloon hong kong tel: (+852) 2245-6100 fax: (+852) 2722-1369 atmel munich gmbh business campus parkring 4 d-85748 garching b. munich germany tel: (+49) 89-31970-0 fax: (+49) 89-3194621 atmel japan 9f, tonetsu shinkawa bldg. 1-24-8 shinkawa chou-ku, tokyo 104-0033 japan tel: (+81) 3523-3551 fax: (+81) 3523-7581 ? 2010 atmel corporation. all rights reserved . / rev.: corp072610 atmel ? , atmel logo and combinations thereof, avr ? , avr studio ? and others are registered trademarks of atmel corporation or its subsidiaries. other terms and product names may be trademarks of others. disclaimer: the information in this document is provi ded in connection with atmel products. no li cense, express or im plied, by estoppel or otherwise, to any intellectual property right is grant ed by this document or in connection with the sale of atmel products. except as set forth in the atmel terms and conditions of sales located on the atmel webs ite, atmel assumes no liability whatsoever and disclaims any express, implied or statut ory warranty relating to its products including, but no t limited to, the implied warranty of merchantability, fitness for a particular purp ose, or non-infringement. in no event shall atmel be liable for any direct, indirect, consequential, punitive, special or incide ntal damages (including, without limitation, damages for loss and profits, business interruption, or loss of information) arising out of the use or inability to use this document, even if at mel has been advised of the possibility of such damages. atmel makes no representations or warranties with respect to the accuracy or completeness of the contents of this document and rese rves the right to make changes to specifications and product descriptions at any time without notice. atmel does not make any commitment to update the information contained herein. unless specifically provided otherwise, atmel products are not suitable for, and s hall not be used in, automotive applications. atmel products are not intended, authorized, or warranted for use as components in applicat ions intended to support or sustain life.

▲Up To Search▲

Price & Availability of AVR32795

	To Download AVR32795 Datasheet File
If you can't view the Datasheet, Please click here to try to view without PDF Reader .